<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.18"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>aws-crt-cpp: AWS Crt Cpp</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">aws-crt-cpp
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.18 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">AWS Crt Cpp </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>C++ wrapper around the aws-c-* libraries. Provides Cross-Platform Transport Protocols and SSL/TLS implementations for C++.</p>
<h2><a class="anchor" id="autotoc_md10"></a>
Currently Included:</h2>
<ul>
<li>aws-c-common: Cross-platform primitives and data structures.</li>
<li>aws-c-io: Cross-platform event-loops, non-blocking I/O, and TLS implementations.</li>
<li>aws-c-mqtt: MQTT client.</li>
<li>aws-c-auth: Auth signers such as Aws-auth sigv4</li>
<li>aws-c-http: HTTP 1.1 client, and websockets (H2 coming soon)</li>
</ul>
<p>More protocols and utilities are coming soon, so stay tuned.</p>
<h1><a class="anchor" id="autotoc_md11"></a>
Building</h1>
<p>The C99 libraries are already included for your convenience as submodules. If you would like to have us build them by default, be sure to either perform a recursive clone <code>git clone --recursive</code> or initialize the submodules via. <code>git submodule update --init</code>. Then, to build, specify the <code>-DBUILD_DEPS=ON</code> CMake argument.</p>
<p>If you want to manage these dependencies manually (e.g. you're using them in other projects), simply specify <code>-DCMAKE_PREFIX_PATH</code> to point to the absolute path where you have them installed.</p>
<h1><a class="anchor" id="autotoc_md12"></a>
Dependencies?</h1>
<h2><a class="anchor" id="autotoc_md13"></a>
Windows and Apple</h2>
<p>There are no non-OS dependencies that AWS does not own, maintain, and ship.</p>
<h2><a class="anchor" id="autotoc_md14"></a>
Unix</h2>
<p>The most likely answer is: none that you should care about.</p>
<p>We do depend on an openssl compatible libcrypto implementation being in your path if you are on a unix system. Note: we do not actually use libssl. The most likely scenario is that libcrypto is already installed on your system. However, since many linux distributions these days do not provide a 32-bit libcrypto package, if you're trying to perform a 32-bit build you will likely need to build and install libcrypto from source.</p>
<h1><a class="anchor" id="autotoc_md15"></a>
Common Usage</h1>
<p>To do anything with IO, you'll need to create a few objects that will be used by the rest of the library.</p>
<p>For example:</p>
<div class="fragment"><div class="line">Aws::Crt::LoadErrorStrings();</div>
</div><!-- fragment --><p>Will load error strings for debugging purposes. Since the C libraries use error codes, this will allow you to print the corresponding error string for each error code.</p>
<div class="fragment"><div class="line">Aws::Crt::ApiHandle apiHandle;</div>
</div><!-- fragment --><p>This performs one-time static initialization of the library. You'll need it to do anything, so don't forget to create one.</p>
<div class="fragment"><div class="line">Aws::Crt::Io::EventLoopGroup eventLoopGroup(&lt;number of threads you want&gt;);</div>
</div><!-- fragment --><p>To use any of our APIs that perform IO you'll need at least one event-loop. An event-loop group is a collection of event-loops that protocol implementations will load balance across. If you won't have very many connections (say, more than 100 or so), then you most likely only want 1 thread. In this case, you want to pass a single instance of this to every client or server implementation of a protocol you use in your application. In some advanced use cases, you may want to reserve a thread for different types of IO tasks. In that case, you can have an instance of this class for each reservation.</p>
<div class="fragment"><div class="line"> Aws::Crt::Io::TlsContextOptions tlsCtxOptions =</div>
<div class="line">    Aws::Crt::Io::TlsContextOptions::InitClientWithMtls(certificatePath.c_str(), keyPath.c_str());</div>
<div class="line">/*</div>
<div class="line"> * If we have a custom CA, set that up here.</div>
<div class="line"> */</div>
<div class="line">if (!caFile.empty())</div>
<div class="line">{</div>
<div class="line">    tlsCtxOptions.OverrideDefaultTrustStore(nullptr, caFile.c_str());</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">uint16_t port = 8883;</div>
<div class="line">if (Io::TlsContextOptions::IsAlpnSupported())</div>
<div class="line">{</div>
<div class="line">    /*</div>
<div class="line">    * Use ALPN to negotiate the mqtt protocol on a normal</div>
<div class="line">    * TLS port if possible.</div>
<div class="line">    */</div>
<div class="line">    tlsCtxOptions.SetAlpnList(&quot;x-amzn-mqtt-ca&quot;);</div>
<div class="line">    port = 443;</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">Aws::Crt::Io::TlsContext tlsCtx(tlsCtxOptions, Io::TlsMode::CLIENT);</div>
</div><!-- fragment --><p>If you plan on using TLS, you will need a TlsContext. These are NOT CHEAP, so use as few as possible to perform your task. If you're in client mode and not doing anything fancy (e.g. mutual TLS), then you can likely get away with using a single instance for the entire application.</p>
<div class="fragment"><div class="line">Aws::Crt::Io::ClientBootstrap bootstrap(eventLoopGroup);</div>
</div><!-- fragment --><p>Lastly, you will need a client or server bootstrap to use a client or server protocol implementation. Since everything is non-blocking and event driven, this handles most of the "callback hell" inherent in the design. Assuming you aren't partitioning threads for particular use-cases, you can have a single instance of this that you pass to multiple clients.</p>
<h1><a class="anchor" id="autotoc_md16"></a>
License</h1>
<p>This library is licensed under the Apache 2.0 License. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.18
</small></address>
</body>
</html>
